home *** CD-ROM | disk | FTP | other *** search
/ Whiteline: Alpha / Whiteline Alpha.iso / progtool / c / tiff_lib / readme. < prev    next >
Encoding:
Text File  |  1994-09-22  |  6.6 KB  |  137 lines
  1. $Header: /usr/people/sam/tiff/libtiff/RCS/README,v 1.2 90/11/24 11:33:34 sam Exp $
  2.  
  3. Configuration Comments:
  4. ----------------------
  5. There is one configuration-related define that you should
  6. set in the Makefile if you want it:
  7.  
  8. SUBFILE_COMPAT  if this is defined in tif_dir.c, an entry will be
  9.                 included in the tag table to support short SubFileType
  10.                 tags, as (incorrectly) generated by earlier versions
  11.                 of this library
  12.  
  13. By default, SUBFILE_COMPAT is not defined.
  14.  
  15. Portability Comments:
  16. --------------------
  17. I run this code on SGI machines (big-endian, MIPS CPU, 32-bit ints,
  18. IEEE floating point).  Makefiles exist for other platforms that
  19. code runs on -- this work has mostly been done by other people.
  20. I've also been told that the code runs on Macintosh and PC-based
  21. systems, although I don't know the particulars.
  22.  
  23. In general, I promise only that the code runs on SGI machines.
  24. I will, however, gladly take back fixes to make it work on other
  25. systems -- when the changes are reasonable unobtrusive.
  26.  
  27. I've tried to isolate as many of the UNIX-dependencies as possible in
  28. two files: tiffcompat.h and tif_compat.c.  There are still some problems
  29. with the use of lseek().  I personally don't care to devote
  30. much effort to making the code work (untouched) on lots of non-UNIX
  31. platforms.
  32.  
  33. Machine dependencies such as byte order are specified in the
  34. file machdep.h.  You DO NOT need to define the floating point
  35. related stuff for the library to compile!  This may be needed
  36. in the future if/when floating point data formats are supported.
  37.  
  38. Two general portability-related defines are:
  39.     USE_VARARGS         define as 0 or 1 to select between the
  40.                         use of varargs.h and stdarg.h; i.e.
  41.                         -DUSE_VARARGS=0 means use stdarg.h
  42.     USE_PROTOTYPES      define as 0 or 1 to select function
  43.                         declarations with parameter types
  44. If you compile the code with prototypes (USE_PROTOTYPES=1), then
  45. you must have USE_VARARGS=0.
  46.  
  47. Beware that if __STDC__ is defined and the USE_* symbols are
  48. NOT defined, then compat.h defines:
  49.     USE_PROTOTYPES      1
  50.     USE_VARARGS         0
  51.  
  52. There is also a control over how to use the C preprocessor to paste
  53. lexical tokens together.  Ansi C defines the ## operator.  This is
  54. used if __STDC__ is defined; otherwise the usual trick is done (see
  55. tiffcompat.h).
  56.  
  57. General Comments:
  58. ----------------
  59. The TIFF library is designed to hide as much of the details of TIFF as
  60. possible.  In particular, TIFF directories are read in their entirety
  61. into an internal format.  This means that only the tags known by the
  62. library are available to a user and that certain tag data may be
  63. maintained that a user doesn't care about (e.g. color response
  64. curves).
  65.  
  66. To add support for a new directory tag the following changes will be
  67. needed:
  68.  
  69. 1. Define the tag in tiff.h.
  70. 2. Add a field to the directory structure in tiffio.h and define a
  71.    FIELD_* bit.
  72. 3. Add an entry in the FieldInfo array defined at the top of tiff_dir.c.
  73. 4. Add entries in TIFFSetField() and TIFFGetField1() for the new tag.
  74. 5. (optional) If the value associated with the tag is not a scalar value
  75.    (e.g. the array for GrayResponseCurve), then add the appropriate
  76.    code to TIFFReadDirectory() and TIFFWriteDirectory().  You're best
  77.    off finding a similar tag and cribbing code.
  78. 6. Add support to TIFFPrintDirectory() in tiff_print.c to print the
  79.    tag's value.
  80.  
  81. To add support for a compression algorithm:
  82.  
  83. 1. Define the tag value in tiff.h.
  84. 2. Edit the file tiff_compress.c to add an entry to the
  85.    CompressionSchemes[] array.
  86. 3. Create a file with the compression scheme code, by convention files
  87.    are named tiff_*.c (except perhaps on System V where the tiff_ prefix
  88.    pushes some filenames over 14 chars.
  89. 4. Edit the Makefile to include the new source file.
  90.  
  91. A compression scheme, say foo, can have up to 6 entry points:
  92.  
  93. TIFFfoo(tif)            /* initialize scheme and setup entry points in tif */
  94. fooPreDecode(tif)       /* called once per strip, after data is read,
  95.                            but before the first row in a strip is decoded */
  96. fooDecode(tif, bp, cc)  /* decode cc bytes of data into the supplied buffer */
  97. fooStripEncode(tif)     /* called once per strip, before the first row in
  98.                            a strip is encoded */
  99. fooEncode(tif, bp, cc)  /* encode cc bytes of user data (bp) */
  100. fooPostEncode(tif)      /* called once per strip, just before data is written */
  101. fooSeek(tif, row)       /* seek forwards row scanlines from the beginning
  102.                            of a strip (row will always be >0 and <rows/strip */
  103. fooCleanup(tif)         /* called when compression scheme is replaced by user */
  104.  
  105. The library handles most I/O buffering.  There are two data buffers
  106. when decoding data: a raw data buffer that holds all the data in a
  107. strip, and a user-supplied scanline buffer that compression schemes
  108. place decoded data into.  When encoding data the data in the
  109. user-supplied scanline buffer is encoded into the raw data buffer (from
  110. where it's written).  Decoding routines should never have to explicitly
  111. read data -- a full strip's worth of raw data is read and scanlines
  112. never cross strip boundaries.  Encoding routines must be cognizant of
  113. the raw data buffer size and call TIFFFlushData1() when necessary.
  114. Note that any pending data is automatically flushed when a new strip is
  115. started, so there's no need do that in the tif_encodestrip routine (if
  116. one exists).
  117.  
  118. The variables tif_rawcc, tif_rawdata, and tif_rawcp in a TIFF structure
  119. are associated with the raw data buffer.  tif_rawcc must be non-zero
  120. for the library to automatically flush data.  The variable
  121. tif_scanlinesize is the size a user's scanline buffer should be.  This
  122. should not be used by compression routines, except where it relates to
  123. the compression algorithm.  That is, the cc parameter to the tif_decode
  124. and tif_encode routines should be used in terminating
  125. decompression/compression.  This ensures these routines can be used,
  126. for example, to decode/encode entire strips of data.
  127.  
  128. In general, if you have a new compression algorithm to add, work from
  129. the code for an existing routine.  In particular, tiff_dumpmode.c has
  130. the trivial code for the "nil" compression scheme, tiff_packbits.c is a
  131. simple byte-oriented scheme that has to watch out for buffer
  132. boundaries, and tiff_lzw.c has the LZW scheme that has the most
  133. complexity -- it tracks the buffer boundary at a bit level.
  134.  
  135. Of course, using a private compression scheme (or private tags) limits
  136. the portability of your TIFF files.
  137.